4.1 Configuring web.oauth2 for end-user based authentication

The MyID authentication web service is called web.oauth2; you must configure this web service to allow access to the API. For end-user based authentication, you do this by configuring the server for acquisition of an access token, secured either by PKCE or a client secret.

Note: Before you begin, you must decide on a client ID for your external system; for example, myid.myclient. This represents your application (for example, website) that intends to make calls to the MyID Core API.

4.1.1 Configuring the authentication service for PKCE

For single-page apps, which run entirely on the client PC, you must secure the request for authentication using PKCE. This ensures that only the caller of the authorization can use the authorization code to request an access token.

First, create a custom client configuration file.

  1. On the MyID web server, navigate to the CustomClients folder.

    By default, this is:

    C:\Program Files\Intercede\MyID\web.oauth2\CustomClients\

    If this folder does not already exist, create it.

  2. In a text editor, create a .json file to contain your client configuration.

    You can use any filename with a .json extension; you are recommended to use the name you have provided for the client as the filename.

    You can create a custom .json file for each client that you want to add. You can include only one client in each file, but you can have multiple files if you need multiple clients. These clients are added to the Clients array from the appsettings.json file. You must use a unique ClientID; if you use the same ClientID in a custom file as an already existing client in the appsettings file, the information from the custom file completely replaces the information in the appsettings.json or appsettings.Production.json override file.

    The order of precedence is:

    • any .json file in the CustomClients folder.

    • appsettings.Production.json

    • appsettings.json

    Note: The appsettings.Production.json file overrides the appsettings.json file not by using the client ID, but by the index of the entry in the Clients array. For this reason, you are recommended not to use the appsettings.Production.json file to provide the details of custom clients, but to use separate files in the CustomClients folder instead.

For more information about custom configuration files, see section 11, Custom configuration files.

Now that you have a custom client configuration file, you can add your client details.

  1. Edit the new file to include the following:

    Copy 
    {
        "ClientId":  "<my client ID>",
        "ClientName":  "<my client name>",
        "AccessTokenLifetime":  <time>,
        "AllowedGrantTypes":  [
            "authorization_code"
        ],
        "RequireClientSecret":  false,
        "RequirePkce":  true,
        "AllowAccessTokensViaBrowser":  true,
        "RequireConsent":  false,
        "AllowedScopes":  [
            "myid.rest.basic"
        ],
        "RedirectUris":  [
            "<callback URL>"
        ]
    }

    where:

    • <my client ID> – the client ID you decided on; for example:

      myid.mysystem

    • <my client name> – an easily readable name for your client system; for example:

      My Client System

    • <time> – the time (in seconds) that the client credential is valid. The default is 3600 – 1 hour.

    • <callback URL> – the URL of the web page on your system to which the authorization code will be returned.

    For example:

    Copy 
    {
        "ClientId":  "myid.myclient",
        "ClientName":  "My Client System",
        "AccessTokenLifetime":  3600,
        "AllowedGrantTypes":  [
            "authorization_code"
        ],
        "RequireClientSecret":  false,
        "RequirePkce":  true,
        "AllowAccessTokensViaBrowser":  true,
        "RequireConsent":  false,
        "AllowedScopes":  [
        "myid.rest.basic"
        ],
        "RedirectUris":  [
            "https://myserver/mysystem/callback.asp"
        ]
    }

  2. Save the configuration file.

  3. Recycle the web service app pool:

    1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
    2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.

    This ensures that the web service has picked up the changes to the configuration file.

  4. Check that the web.oauth2 server is still operational by logging on to the MyID Operator Client.

    Application setting JSON files are sensitive to such issues as comma placement; if the format of the file is not correct, the web service cannot load the file and will not operate, which may result in an error similar to:

    HTTP Error 500.30 - ANCM In-Process Start Failure

    See section 14, Troubleshooting for information on resolving problems that cause HTTP Error 500.30.

You can now obtain an access token; see section 4.2, Obtaining an end-user based access token using PKCE.

4.1.2 Configuring the authentication service for a client secret

For stateful websites, where for example the server uses cookies to map stateful sessions between the client and the web server, it is recommended to configure the authentication service to require a client secret; you do not have to use PKCE, but you can use it in addition to the client secret if you want.

Note: The following instructions assume that you are using a client secret without PKCE. If you want to use both a client secret and PKCE, you can set both the RequireClientSecret and RequirePkce options to true, and then combine the requests for an authentication code and access token from section 4.2, Obtaining an end-user based access token using PKCE and section 4.3, Obtaining an end-user based access token using a client secret.

Before you edit the configuration file, create a client secret; see section 3.2.1, Creating a shared secret.

First, create a custom client configuration file.

  1. On the MyID web server, navigate to the CustomClients folder.

    By default, this is:

    C:\Program Files\Intercede\MyID\web.oauth2\CustomClients\

    If this folder does not already exist, create it.

  2. In a text editor, create a .json file to contain your client configuration.

    You can use any filename with a .json extension; you are recommended to use the name you have provided for the client as the filename.

    You can create a custom .json file for each client that you want to add. You can include only one client in each file, but you can have multiple files if you need multiple clients. These clients are added to the Clients array from the appsettings.json file. You must use a unique ClientID; if you use the same ClientID in a custom file as an already existing client in the appsettings file, the information from the custom file completely replaces the information in the appsettings.json or appsettings.Production.json override file.

    The order of precedence is:

    • any .json file in the CustomClients folder.

    • appsettings.Production.json

    • appsettings.json

    Note: The appsettings.Production.json file overrides the appsettings.json file not by using the client ID, but by the index of the entry in the Clients array. For this reason, you are recommended not to use the appsettings.Production.json file to provide the details of custom clients, but to use separate files in the CustomClients folder instead.

For more information about custom configuration files, see section 11, Custom configuration files.

Now that you have a custom client configuration file, you can add your client details:

  1. Edit the new file to include the following:

    Copy 
    {
        "ClientId":"<my client ID>",
        "ClientName":"<my client name",
        "AccessTokenLifetime": <time>,
        "AllowedGrantTypes":[
            "authorization_code"
        ],
        "RequireClientSecret":true,
        "RequirePkce":false,
        "AllowAccessTokensViaBrowser":true,
        "RequireConsent":false,
        "ClientSecrets":[
            {
                "Value":"<secret>"
            }
        ],
        "AllowedScopes":[
            "myid.rest.basic"
        ],
        "RedirectUris":[
            "<callback URL>"
        ]
    }

    where:

    • <my client ID> – the client ID you decided on; for example:

      myid.mysystem

    • <my client name> – an easily readable name for your client system; for example:

      My Client System

    • <time> – the time (in seconds) that the client credential is valid. The default is 3600 – 1 hour.

    • <secret> – the Base64-encoded SHA-256 hash of the secret you created; for example:

      kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk=

    • <callback URL> – the URL of the web page on your system to which the authorization code will be returned.

    For example:

    Copy 
    {
        "ClientId":"myid.myclient",
        "ClientName":"My Client System",
        "AccessTokenLifetime":3600,
        "AllowedGrantTypes":[
            "authorization_code"
        ],
        "RequireClientSecret":true,
        "RequirePkce":false,
        "AllowAccessTokensViaBrowser":true,
        "RequireConsent":false,
        "ClientSecrets":[
            {
                "Value":"kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk="
            }
        ],
        "AllowedScopes":[
            "myid.rest.basic"
        ],
        "RedirectUris":[
            "https://myserver/mysystem/callback.asp"
        ]
    }

  2. Save the configuration file.

  3. Recycle the web service app pool:

    1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
    2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.

    This ensures that the web service has picked up the changes to the configuration file.

  4. Check that the web.oauth2 server is still operational by logging on to the MyID Operator Client.

    Application setting JSON files are sensitive to such issues as comma placement; if the format of the file is not correct, the web service cannot load the file and will not operate, which may result in an error similar to:

    HTTP Error 500.30 - ANCM In-Process Start Failure

    See section 14, Troubleshooting for information on resolving problems that cause HTTP Error 500.30.

You can now obtain an access token; see section 4.3, Obtaining an end-user based access token using a client secret.

4.1.3 Cross-origin resource sharing

Cross-origin resource sharing (CORS) defines a way for web applications on one domain to interact with resources on other domains; for example, if you create a website on one domain that uses end-user authentication, then using the access token to call the MyID Core API on another domain, you must configure the MyID web.oauth2 and rest.core services to allow CORS.

To allow CORS:

  1. In a text editor, open the custom client configuration file you created.

    By default, this is:

    C:\Program Files\Intercede\MyID\web.oauth2\appsettings.Production.json

  2. In the client you set up for your external system, add the following:

    Copy 
    "AllowedCorsOrigins": [
        "<external origin>"
    ]

    where:

    • <external origin> is the URL from which you are going to call the API. You can add multiple origins if necessary.

      Note: Make sure you use an origin, and not an URL, when configuring CORS. For example: https://myserver/ is an URL, while https://myserver is an origin.

    For example:

    Copy 
    {
        "ClientId":"myid.myclient",
        "ClientName":"My Client System",
        "AccessTokenLifetime":3600,
        "AllowedGrantTypes":[
            "authorization_code"
        ],
        "RequireClientSecret":true,
        "RequirePkce":false,
        "AllowAccessTokensViaBrowser":true,
        "RequireConsent":false,
        "ClientSecrets":[
            {
                "Value":"kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk="
            }
        ],
        "AllowedScopes":[
            "myid.rest.basic"
        ],
        "RedirectUris":[
            "https://myserver/mysystem/callback.asp"
        ],
             "AllowedCorsOrigins": [
                "http://myexternalserver"
        ]
    }

  3. Save the configuration file and recycle the web.oauth2 app pool.

  4. In a text editor, open the appsettings.Production.json file for the rest.core service.

    By default, this is:

    C:\Program Files\Intercede\MyID\rest.core\appsettings.Production.json

    This file is the override configuration file for the appsettings.json file for the web service. If this file does not already exist, you must create it in the same folder as the appsettings.json file, and include the following:

    Copy 
    {
        "MyID":  {
            "Cors":  {
                "AllowedOrigins":  [
                    "<external origin>"
                ],
            },
       }
    }

    where:

    • <external origin> is the URL from which you are going to call the API. You can add multiple origins if necessary.

      Note: Make sure you use an origin, and not an URL, when configuring CORS. For example: https://myserver/ is an URL, while https://myserver is an origin.

    If the appsettings.Production.json file already exists, add the above Cors:AllowedOrigins section to the file.

    For example:

    Copy 
    {
        "MyID":  {
            "Cors":  {
                "AllowedOrigins":  [
                    "http://myexternalserver"
                ],
            },
       }
    }

  5. Save the configuration file and recycle the rest.core app pool.

4.1.3.1 Troubleshooting CORS

If you see an error similar to the following in your browser console:

Access to XMLHttpRequest at 'https://myserver/rest.core/api/People?q=*' from origin 'http://myexternalserver:5500' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

suggests that the AllowedOrigins option in the rest.core appsettings.Production.json file, or the AllowedCorsOrigins option in the web.oauth2 custom client configuration file, has not been set up correctly.